Hermes Agent完全实战指南

前言

用过 Claude Code 或 Codex CLI 的人大概都有这个体验:Agent 本身挺强,但你得花大量时间给它"搭环境"——写 AGENTS.md、写验证脚本、设计 Skills、维护进度文件、配置 MCP、管理上下文。Agent 的大部分失败不是模型不会写代码,而是周围的工程基础设施没跟上。

这套基础设施,业界叫 Harness——给 Agent 准备的操作环境和约束系统。问题是,搭 Harness 本身就是一个工程量巨大的事,一个资深工程师可能需要几周才能把一个项目的 Harness 搭到位。

然后 Nous Research 做了一件事:把 Harness 产品化,做成了一个开箱即用的 Agent 框架。

这就是 Hermes Agent——MIT 协议开源,2026 年 2 月发布,两个月拿下 27K+ Stars。

一句话概括:Hermes Agent 不是又一个"更聪明的 AI 编码工具"。它是一个自带三层记忆、自动生成 Skills、支持 15+ 平台的 Agent 操作系统——别的工具让你自己搭 Harness,Hermes 出厂就带。


1. Hermes Agent 是什么

1.1 先说人话

Hermes Agent 是 Nous Research 做的开源 AI Agent 框架。它和 Claude Code、Codex CLI 最大的区别在于:它不只是一个编码助手,它是一个可以 24/7 自主运行的个人 AI Agent。

它能接入 200+ 个模型(不锁定厂商),通过 Telegram、Discord、Slack、微信、飞书等 15+ 个平台跟你对话,而且——它会记住你,会从经验中自动生成工作流,下次遇到类似问题直接调用,越用越顺手。

1.2 一张表看定位

维度 Claude Code Codex CLI Hermes Agent
定位 交互式编码 Agent 后台编码 Agent 全能个人 AI Agent
模型绑定 Claude only OpenAI only 200+ 模型(OpenRouter、Anthropic、OpenAI、Gemini、本地模型)
运行模式 人在回路,实时交互 后台任务,异步执行 两者都支持 + 7x24 自主运行
记忆 手动维护 CLAUDE.md 无持久记忆 三层自动记忆(Session + Persistent + Skill)
Skills 手动编写 SKILL.md 无 自动生成 + 自动修正 + 社区 Hub
对话平台 终端 CLI 终端 CLI 15+ 平台(Telegram、Discord、微信、飞书等)
IDE 集成 VS Code、JetBrains VS Code ACP 适配器(VS Code、Zed、JetBrains)
代码智能 LSP、AST 感知 终端 + 文件操作 终端 + 文件操作(无 LSP)
开源 否 是(MIT) 是(MIT)
最适合 复杂编码和重构 批量编码任务 个人助理 + 跨平台自动化 + 持久任务

一个关键区分:Claude Code 是"白天的结对编程搭档",Hermes 是"全天候的个人 AI 助理"。 大多数重度用户会同时用两者——Claude Code 负责交互式编码,Hermes 负责持久任务、定时调度、跨平台消息处理。


2. 架构全景

2.1 五层架构

flowchart TB
    subgraph L1["Layer 1: 对话入口"]
        CLI["终端 CLI / TUI"]
        TG["Telegram"]
        DC["Discord"]
        SL["Slack"]
        WX["微信 / 飞书 / 钉钉"]
        MORE["Signal / WhatsApp / Email / SMS / ..."]
    end

    subgraph L2["Layer 2: Gateway 统一网关"]
        GW["GatewayRunner
会话管理 + 平台适配"] end subgraph L3["Layer 3: Agent 核心"] LOOP["AIAgent 主循环
消息 → 工具调用 → 结果 → 循环"] MEM["三层记忆
Session + Persistent + Skill"] CTX["上下文压缩
保护头尾,压缩中间"] end subgraph L4["Layer 4: 工具层"] TOOLS["60+ 内建工具"] MCP["MCP Client
6000+ 外部应用"] PLUGIN["插件系统
14 个生命周期 Hook"] end subgraph L5["Layer 5: 执行后端"] LOCAL["本地终端"] DOCKER["Docker"] SSH["SSH"] MODAL["Modal Serverless"] DAYTONA["Daytona"] end L1 --> L2 --> L3 --> L4 --> L5

2.2 项目目录结构

hermes-agent/
├── run_agent.py              # AIAgent 类,核心对话循环(~625KB)
├── model_tools.py            # 工具编排层:发现、分发、Schema 提供
├── toolsets.py               # Toolset 定义和解析
├── cli.py                    # HermesCLI 类,交互式终端
├── hermes_state.py           # SessionDB,SQLite + FTS5 全文搜索
├── agent/                    # Agent 内部组件
│   ├── anthropic_adapter.py  # Anthropic 原生适配器
│   ├── gemini_native_adapter.py
│   ├── bedrock_adapter.py
│   ├── memory_manager.py     # 可插拔记忆后端
│   ├── prompt_builder.py     # Prompt 构建(Skills 注入)
│   ├── context_compressor.py # 上下文压缩
│   ├── skill_utils.py        # Skill 加载和匹配
│   └── shell_hooks.py        # Shell Hook 系统(兼容 Claude Code 协议)
├── tools/                    # 60+ 工具实现
│   ├── registry.py           # 自注册工具中心
│   ├── delegate_tool.py      # Subagent 委派
│   ├── skill_manager_tool.py # Skill 管理
│   └── environments/         # 执行后端(Local、Docker、SSH、Modal...)
├── skills/                   # 内建 Skills(按分类目录组织)
├── optional-skills/          # 可选 Skills(按需安装)
├── gateway/                  # 消息网关
│   ├── run.py                # GatewayRunner
│   └── platforms/            # 15+ 平台适配器
├── plugins/                  # 插件系统
├── cron/                     # 定时任务调度器
├── acp_adapter/              # IDE 集成(VS Code / Zed / JetBrains)
├── ui-tui/                   # Ink (React/TypeScript) 终端 UI
├── AGENTS.md                 # AI 编码工具的开发指南(752 行)
└── config.yaml               # 统一 YAML 配置

3. 工具系统:60+ 工具的自注册模式

3.1 先说人话

Hermes 的工具不需要手动注册。每个工具文件在被 import 时自动向中央注册表声明自己——名字、所属 Toolset、JSON Schema、处理函数。这意味着加一个新工具只需要写一个 Python 文件,不用改任何配置。

3.2 注册机制

# tools/my_tool.py
from tools.registry import registry

registry.register(
    name="my_tool",
    toolset="hermes-cli",
    schema={
        "type": "function",
        "function": {
            "name": "my_tool",
            "description": "做某件事",
            "parameters": {
                "type": "object",
                "properties": {
                    "input": {"type": "string", "description": "输入内容"}
                },
                "required": ["input"]
            }
        }
    },
    handler=my_handler_function
)

发现过程:model_tools.py 调用 discover_builtin_tools(),用 AST 解析每个 tools/*.py 文件,找到包含 registry.register() 调用的模块才 import——不会盲目导入所有文件,避免了循环依赖。

3.3 Toolset 分组

工具通过 Toolset 分组,不同场景加载不同工具集:

Toolset 用途 包含工具数
_HERMES_CORE_TOOLS 所有平台共享的核心工具 ~30
hermes-cli 终端交互 核心 + CLI 专属
hermes-telegram Telegram 对话 核心 + 消息专属
hermes-acp IDE 集成 核心 - 音频 - 澄清 UI
web / browser 网页操作 浏览器自动化工具
safe 安全模式 去掉终端执行等高风险工具

Toolset 支持递归包含(includes 字段),组合灵活。

3.4 工具调用流程

flowchart LR
    A["AIAgent 主循环"] --> B["model_tools.handle_function_call()"]
    B --> C["coerce_tool_args()
类型强转(防 LLM 字符串漂移)"] C --> D["Plugin pre_tool_call Hook
可阻断"] D --> E["registry.dispatch()
执行工具处理函数"] E --> F["Plugin post_tool_call Hook"] F --> G["Plugin transform_tool_result Hook"] G --> H["返回结果给 Agent 循环"]

有四个特殊工具(todo、memory、session_search、delegate_task)被 Agent 主循环直接拦截处理,不走通用分发流程——因为它们需要访问 Agent 的内部状态。


4. 三层记忆:Session / Persistent / Skill

4.1 先说人话

大多数 AI 工具的记忆是"一次性的"——关掉窗口就忘了。Claude Code 的 CLAUDE.md 好一些,但需要你手动维护。

Hermes 的记忆是自动的、三层的、跨会话持久的。它不是把所有历史塞进 context——而是按需检索,只拿相关的部分。

4.2 三层结构

层 存储位置 内容 生命周期
Session(会话) SQLite + FTS5 完整对话记录,全文索引 永久存储,按需检索
Persistent(持久) ~/.hermes/memories/MEMORY.md + USER.md Agent 笔记 + 用户画像 跨会话持久,每次加载
Skill(技能) ~/.hermes/skills/*.md 结构化工作流 跨会话持久,自动匹配加载

4.3 关键工程细节

持久记忆有硬上限。 MEMORY.md 限制在 2,200 字符(~800 tokens),USER.md 限制在 1,375 字符(~500 tokens)。这不是偷懒——每个记忆 token 都是不可缓存的 system prompt token,上限太高会直接拉高 API 成本。

冻结快照模式。 记忆在会话开始时一次性快照,中途的写入只存到磁盘、不影响当前会话。这是一个精心设计:保护 Anthropic 的 prefix cache,避免每次记忆变更都让缓存失效。大部分团队在自建 Agent 时会忽略这个优化,导致 API 成本翻倍。

文件锁。 用 fcntl(Unix)/ msvcrt(Windows)防止多个 Agent 进程同时写入记忆文件导致数据损坏。

注入扫描。 每次写入记忆前都会扫描内容,检测 prompt injection 模式、凭证外泄指令(curl/wget 带 token)、SSH 后门签名等。

4.4 按需检索 vs 全量加载

传统做法是把所有历史塞进 context window。Hermes 的做法是 FTS5 全文搜索——只检索当前任务相关的历史片段。

这意味着你可以积累几个月的对话历史,而不会降低 Agent 的响应质量或拖慢速度。


5. 自进化 Skills:从经验中自动生成工作流

5.1 先说人话

Claude Code 的 Skills 需要你手动写 SKILL.md。Hermes 的 Skills 是Agent 自己写的——做完一个复杂任务后,它会自动把步骤提炼成一个 Skill 文件,下次遇到类似问题直接调用。

用户纠正了 Agent 的做法?它会自动更新对应的 Skill。这就是"自进化"的含义——不是 Agent 改自己的代码,而是 Agent 改自己的行为指令。

5.2 Skill 文件结构

---
name: k8s-pod-debug
description: 排查 K8s Pod 启动失败
version: 1.0.0
platforms: [linux, macos]
metadata:
  hermes:
    tags: [Kubernetes, 排障]
    category: devops
prerequisites:
  commands: [kubectl]
---
# K8s Pod 启动失败排查

## 步骤
1. `kubectl get pods -n <namespace>` 确认 Pod 状态
2. 如果 ImagePullBackOff → `kubectl describe pod` 看 Events
3. 如果 CrashLoopBackOff → `kubectl logs` 看应用日志
4. 定位根因后,最小化修改 YAML
5. `kubectl apply` 后验证 Pod 恢复 Running

Skills 是 Markdown——是数据,不是代码。它塑造 prompt,但不修改 Agent 源码。用户可以随时审查、编辑或删除任何 Skill。

5.3 Skill 来源

来源 说明
内建 skills/ 目录,40+ 个预置 Skill(Apple、GitHub、MLOps、创意写作等)
可选 optional-skills/,较重的 Skill,按需安装:hermes skills install official/<category>/<skill>
Agent 自动生成 从复杂任务中提炼,存入 ~/.hermes/skills/
社区 Hub 兼容 agentskills.io 标准,一键安装社区 Skill
用户自建 手动放入 ~/.hermes/skills/

5.4 自进化循环

flowchart TB
    A["完成一个复杂任务"] --> B{"自动回顾"}
    B -->|"有什么要记住的?"| C["写入 MEMORY.md"]
    B -->|"这是个重复模式?"| D["自动创建 Skill"]
    B -->|"用户纠正了?"| E["更新现有 Skill"]
    D --> F["下次遇到类似问题
自动匹配并调用 Skill"] E --> F C --> F

5.5 需要清醒认识的地方

"自进化"听起来很科幻,但实际机制很朴素。 源码级审计(Saulius.io 的分析)表明,Hermes 的"自进化"分解为四个正交机制:

  1. Skill 自动生成:从任务轨迹中提炼 Markdown 文件
  2. 持久记忆:自动整理用户偏好和习惯
  3. 离线 RL 微调:收集轨迹数据供人工监督的微调(用户必须手动触发 rl_start_training,Agent 不会自行启动)
  4. Pull 更新:hermes update 拉取上游代码

没有任何一个机制涉及 Agent 自主修改源码、自动重写 prompt、或自主评分改进。 真正的递归自我改进仍然是学术前沿。

但这不影响它的实用性。一个会自动写笔记、自动总结 SOP、自动记住你偏好的 Agent,已经比 90% 的"每次从零开始"的工具好用太多了。


6. 多平台 Gateway

6.1 先说人话

Claude Code 和 Codex CLI 只能在终端里用。Hermes 可以同时连接 15+ 个消息平台——你在 Telegram 上问的问题、在终端里的后续操作、在 Discord 里的追问,共享同一个记忆和上下文。

6.2 支持平台

平台 特殊能力
Telegram 语音转文字、菜单自动生成
Discord 服务器 + 私信
Slack 频道 + 私信
WhatsApp 通过 API
Signal 端到端加密
微信 / 企业微信 媒体上传
飞书 / Lark 机器人接口
钉钉 机器人接口
Matrix 去中心化协议
Mattermost 自托管
Email 收发邮件
SMS 通过 Twilio
Home Assistant 智能家居控制
Open WebUI Web 界面
API Server 自定义集成

6.3 架构要点

Gateway 是一个统一进程,同时管理所有平台的连接。核心设计:

这是 Hermes 最独特的组件,也是它与纯编码工具拉开定位差距的地方。


7. 安全五道防线

7.1 先说人话

一个能读写文件、执行命令、访问 API 的 Agent,安全问题不是可选项。Hermes 内建了五道防线,不需要额外配置。

7.2 五道防线详解

防线 机制 防什么
记忆注入扫描 正则检测 prompt injection、凭证外泄指令、角色劫持 防止恶意内容通过记忆系统注入
上下文文件注入扫描 检测 AGENTS.md 等文件中的隐形 Unicode、隐藏 HTML div、注入模式 防止项目文件被植入攻击指令
MCP 包 OSV 检查 启动 MCP Server 前验证 npm/pypi 包是否有已知漏洞 防止恶意依赖
凭证脱敏 从所有终端输出和聊天记录中剥离 API Key、Token、Secret 防止密钥泄露
结构化上下文压缩 压缩中间对话时用 Resolved/Pending 追踪 + "不同助手"移交帧 防止被压缩的旧指令被重新执行

独立评估的结论:这五道防线"对任何 Agent 都有独立价值",即使你不用 Hermes 也值得参考。

但也要注意边界:Hermes 明确声明安全模型是"保护运营者免受 LLM 行为影响,不防御恶意共租户"。个人使用足够,多租户场景需要额外加固。


8. 实战:从安装到体验学习循环

8.1 安装

三种部署方式,推荐从本地安装开始:

# 方式一:本地安装(macOS / Linux / WSL2)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 方式二:Docker(适合 7x24 运行)
docker pull nousresearch/hermes-agent
docker run -v ~/.hermes:/root/.hermes nousresearch/hermes-agent

# 方式三:$5 VPS(推荐的长期运行方案,内存占用 < 500MB)
# 在任意 VPS 上执行方式一的安装脚本即可

8.2 首次配置

安装后运行 hermes,首次会启动配置向导。核心配置在 ~/.hermes/config.yaml:

# ~/.hermes/config.yaml(关键配置项)

# 模型选择——不绑定厂商
model:
  provider: openrouter          # 或 anthropic / openai / ollama
  model: anthropic/claude-sonnet-4-20250514
  # 也可以用便宜模型做日常对话
  cheap_model: deepseek/deepseek-chat

# 工具集
toolsets:
  - hermes-cli
  - web
  - browser

# Skills 配置
skills:
  auto_improve: true            # 允许 Agent 自动创建和修改 Skills
  external_dirs:                # 额外 Skill 目录
    - ~/my-skills/

# 消息网关(按需启用)
gateway:
  telegram:
    enabled: true
    token: "YOUR_BOT_TOKEN"
  discord:
    enabled: false

API Key 放在 ~/.hermes/.env,不放 config.yaml:

# ~/.hermes/.env
OPENROUTER_API_KEY=sk-or-...
ANTHROPIC_API_KEY=sk-ant-...

8.3 体验自进化循环

启动 Hermes 后,做一个稍微复杂的任务:

> 帮我查一下 production 命名空间里所有 Pod 的资源使用情况,
  找出 CPU request 超过 500m 但实际用量不到 100m 的 Pod,
  生成一个优化建议

Agent 会:

  1. 执行 kubectl top pods 和 kubectl get pods -o json
  2. 交叉比对 request 和实际用量
  3. 输出优化建议

任务完成后,自动回顾触发:

[Hermes] 检测到这是一个可复用的工作流。
已创建 Skill: k8s-resource-audit
位置: ~/.hermes/skills/k8s-resource-audit/SKILL.md

下次你说"帮我查一下资源浪费的 Pod",Agent 会直接调用这个 Skill,不再从零推理步骤。

如果你纠正了它——"下次先检查是否有 VPA 在管理这些 Pod"——它会更新 Skill 文件,加上 VPA 检查步骤。

8.4 跨平台对话

在终端里启动 Gateway:

hermes gateway start

然后在 Telegram 上给你的 Hermes Bot 发消息:

刚才那个 K8s 资源审计的结果,帮我发到 #ops-alerts Slack 频道

Hermes 记得你刚才的分析结果(跨平台共享记忆),直接执行。


9. 插件系统与 Hook

9.1 14 个生命周期 Hook

插件可以在 Agent 生命周期的 14 个节点注入逻辑:

Hook 触发时机 典型用途
pre_tool_call 工具执行前 权限控制、参数校验
post_tool_call 工具执行后 日志记录、结果缓存
transform_tool_result 工具结果返回前 脱敏、格式化
pre_llm_call LLM 调用前 注入额外上下文
post_llm_call LLM 调用后 Token 统计、成本追踪
on_session_start 会话开始 加载项目上下文
on_session_end 会话结束 生成摘要

9.2 Shell Hook 兼容 Claude Code

Hermes 的 Shell Hook 系统(agent/shell_hooks.py)刻意兼容 Claude Code 的 Hook 协议。它同时接受两种格式:

// Claude Code 格式
{"decision": "block", "reason": "不允许删除生产数据库"}

// Hermes 原生格式
{"action": "block", "message": "不允许删除生产数据库"}

这意味着你已有的 Claude Code Hook 脚本可以直接复用。


10. Subagent 委派

10.1 机制

Hermes 通过 delegate_tool.py 实现子 Agent 委派。主 Agent 可以生成隔离的子 Agent 来处理并行任务。

关键限制:

这些限制是刻意的——防止失控的递归调用和权限扩散。

10.2 与 Claude Code 对比

维度 Claude Code Hermes Agent
子 Agent 机制 Agent tool + Task tool,原生 Teams 支持 delegate_tool,线程隔离
最大深度 无硬性限制 2 层
并发数 无硬性限制 3 个
子 Agent 权限 继承父 Agent 受限(无记忆、无消息、无代码执行)

11. 优势与局限

11.1 优势

多平台 Gateway 是独一份。 15+ 消息平台的统一接入,对话跨平台共享记忆——这是 Claude Code 和 Codex CLI 完全没有的能力。

模型自由。 200+ 模型随意切换,支持 OpenRouter 路由、本地 Ollama 模型、甚至中途换模型。不被任何厂商锁定。

自进化 Skills 降低维护成本。 不需要手动写 SKILL.md,Agent 从经验中自动生成和修正。对个人用户来说,这比手动维护 Harness 高效得多。

安全五道防线开箱即用。 不需要额外配置就有记忆注入扫描、凭证脱敏、MCP 漏洞检查。

部署成本极低。 一台 $5/月的 VPS,内存占用 < 500MB,就能 7x24 运行。

11.2 局限

编码能力不如 Claude Code。 没有 LSP、没有 AST 感知、没有原生 IDE 深度集成。做复杂的多文件重构,Claude Code 明显更强。

单体架构的维护风险。 CLI、Gateway、60+ 工具、RL 训练、15 个平台适配器全在一个仓库里。独立评估指出有 ~1,800 个 open issue,只有 30 个贡献者——"功能速度优先于稳定性"的信号。

自进化的审计缺口。 Skills 会自动修改,虽然改动是可 diff 的 Markdown,但现实是大多数用户不会去审查。"你能审计"和"你会审计"之间有很大的差距。在模糊领域,Agent 可能"越来越快、越来越自信地做错事"。

数据飞轮动机。 轨迹保存和 RL 组件的存在是为了给 Nous Research 的未来模型生成训练数据。这是透明的(MIT 协议、有文档说明),但值得了解。

测试套件有问题。 项目自己的文档警告不要直接运行 pytest,需要用 wrapper 脚本统一环境——说明测试和本地环境有耦合问题。


12. 决策指南

你需要一个 7x24 自主运行的 AI 助理吗?
  → 是:Hermes Agent(这是它的主场)
  → 否 ↓

你的核心需求是高质量代码编写和重构?
  → 是:Claude Code(LSP + AST 感知,编码质量最强)
  → 否 ↓

你需要跨 Telegram / Discord / 微信等平台的 AI 对话?
  → 是:Hermes Agent(唯一选择)
  → 否 ↓

你想避免厂商锁定,需要接入多种模型?
  → 是:Hermes Agent(200+ 模型)
  → 否 ↓

你需要后台批量处理编码任务?
  → 是:Codex CLI
  → 否:Claude Code(最成熟、最稳定的默认选择)

最务实的组合:Claude Code 当白班(交互式编码),Hermes 当夜班(持久任务、定时调度、跨平台消息)。


13. 核心参考资料

资料 来源
Hermes Agent 官方仓库 github.com/NousResearch/hermes-agent
Hermes Agent 官方文档 hermes-agent.nousresearch.com/docs
源码级架构审计:"自进化"到底意味着什么 saulius.io
独立技术评估(架构、优势、红旗) michaeloboyle/gist
2026 CLI Agent 横评(含 Hermes) colombani.ai
Hermes Agent 30 天使用报告 heyuan110.com
Hermes 自进化 AI 深度剖析 dev.to/marwane
Hermes vs Claude Code vs OpenClaw 三方对比 utilo.io
Agent 自进化战争 towardsai.net
Hermes 记忆系统五层拆解 dev.to/openwalrus